Skip to content

feat: add numerical enum generation support - #8532

Open
Hardik K (hardikkaurani) wants to merge 4 commits into
microsoft:mainfrom
hardikkaurani:feat/numerical-enum-generation
Open

Hardik K (hardikkaurani) wants to merge 4 commits into
microsoft:mainfrom
hardikkaurani:feat/numerical-enum-generation

Conversation

@hardikkaurani

Copy link
Copy Markdown
Contributor

Closes #5165

Problem

OpenAPI definitions frequently define numerical enums (e.g., type: integer, format: int32, enum: [10, 20, 30] or with x-ms-enum value mappings). Previously, Kiota's generator pipeline:

  1. Explicitly bypassed numerical enums in schema analysis (OpenApiSchemaExtensions.IsEnum checked only JsonValueKind.String with an explicit comment // number and boolean enums are not supported), causing numeric enums to fall back to primitive integer types instead of creating strongly-typed CodeEnum definitions.
  2. Lacked IsNumeric and numeric format representation on CodeEnum and CodeEnumOption in the CodeDOM.
  3. Language writers assumed sequential 0-based positions (iota in Go, sequential flag powers, or no value assignments in C#), which could not preserve non-contiguous, non-zero-based, or negative wire values. In Go, evaluating [i] on non-contiguous enum values resulted in runtime array index out-of-range panics.

Root cause

  • OpenApiSchemaExtensions.IsEnum: Guarded against any schema whose enum entries were not string literals.
  • CodeDOM: CodeEnum and CodeEnumOption had no property capturing whether the enum is numerical or preserving its numeric format (e.g. int64).
  • Language Writers: Writers for C#, TypeScript, Python, Go, PHP, and Ruby emitted quotes or sequential positions instead of explicit numeric literal constants corresponding to their wire values.

Implementation

  1. Schema Parsing & CodeDOM:
    • Updated OpenApiSchemaExtensions.IsEnum to accept JsonValueKind.Number in addition to JsonValueKind.String.
    • Added IsNumeric and Format properties to CodeEnum and IsNumeric to CodeEnumOption.
    • In KiotaBuilder.AddEnumDeclaration and SetEnumOptions, populated IsNumeric when the schema is an integer/number schema or contains numeric enum items, preserving the numeric wire value in SerializationName.
  2. Language Writers:
    • C# (CodeEnumWriter.cs): When IsNumeric is true, emits explicit member values (Option = 10,) and appends underlying type suffixes for integer formats (e.g. : long for int64, : sbyte, : short, etc.), while preserving [EnumMember(Value = "...")].
    • TypeScript (CodeConstantWriter.cs, CodeFunctionWriter.cs): Emits numeric literals in EnumObject (Option: 10,) allowing (typeof Enum)[keyof typeof Enum] to yield a numeric literal union. Added WireName fallback for enum default values.
    • Python (CodeEnumWriter.cs): Inherits from (int, Enum) (or (float, Enum)) and emits numeric literals (Option = 10,).
    • Go (CodeEnumWriter.cs): Emits explicit integer constants (OPTION_TYPE Type = 10, int64 for int64 format) and generates a safe switch i statement in String() to prevent out-of-range slice access panics on non-contiguous values.
    • PHP (CodeEnumWriter.cs): Emits integer class constants (public const OPTION = 10;).
    • Ruby (CodeEnumWriter.cs): Emits numeric values in frozen enum hash (Option: 10).

Compatibility

  • Existing string enums remain 100% backward compatible: IsNumeric defaults to false, retaining identical output across all language writers.
  • Mixed or string-wrapped numbers (e.g. type: string with enum: ['+1', '-1']) continue to be treated as string enums.

Serialization & Runtime Follow-up

  • Generator Scope: Generates strongly-typed numeric enums with their exact OpenAPI wire values preserved across target languages.
  • Runtime Dependency Coordination: While the generator now emits correct numeric values (e.g., CLR numeric values matching wire values in C# and numeric literal types in TypeScript/Python), full end-to-end JSON number token serialization and deserialization in certain runtime client libraries (such as kiota-dotnet, kiota-typescript, kiota-python) currently require runtime library coordination as discussed in kiota-dotnet PR - fixes a bug where query parameters would be missing in go #843. This generator change establishes the prerequisite foundation across languages.

Maintainer context

Addresses architectural feedback from Vincent Biret (@baywet) on microsoft/kiota-dotnet#843:

"This is not going to work consistently across languages. The generator would need to be updated first to support generating numerical values, and then we'd need to coordinate implementation accross languages."

Tests

  • KiotaBuilderTests:
    • ParsesNumericalEnumInformationAsync: Verifies type: integer, format: int32, enum: [10, 20, 30] generates a CodeEnum with IsNumeric == true, Format == "int32", and correct options.
    • ParsesNumericalEnumWithNegativeAndSparseValuesAsync: Verifies negative (-1), zero (0), and sparse non-contiguous (100) values with int64 format.
    • ParsesNumericalEnumWithXMsEnumNamesAsync: Verifies x-ms-enum option names and descriptions are preserved with numeric wire values.
  • Language Writer Tests:
    • C#: WritesNumericalEnumWithExplicitValues, WritesNumericalEnumWithInt64Format, WritesNumericalEnumWithNegativeValues.
    • TypeScript: WritesNumericalEnum.
    • Python: WritesNumericalEnum.
    • Go: WritesNumericalEnum, WritesNumericalEnumWithInt64Format.
    • PHP: WritesNumericalEnumAsync.
    • Ruby: WritesNumericalEnum.
  • Executed dotnet test ./tests/Kiota.Builder.Tests/Kiota.Builder.Tests.csproj --filter "FullyQualifiedName~NumericalEnum" (all 12 passed) and full CodeEnumWriterTests (all 75 passed).

Copilot AI balanced review requested due to automatic review settings November 2, 2026 17:27
@hardikkaurani
Hardik K (hardikkaurani) requested a review from a team as a code owner November 2, 2026 17:27

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet), following your architectural feedback on microsoft/kiota-dotnet#843 regarding generator-first support for numerical enums, this PR updates the Kiota generator pipeline (OpenAPI schema analysis, CodeDOM, and language writers) to support numerical enums and resolves #5165.

Whenever you have a moment, I'd appreciate your review and guidance on coordinating any downstream runtime changes.

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Thanks for opening this pull request! Please add a changelog entry under ## [Unreleased] in CHANGELOG.md, before the first released version section, so users can see what changed. Add bug fixes under ### Changed and new features under ### Added.

@hardikkaurani
Hardik K (hardikkaurani) force-pushed the feat/numerical-enum-generation branch from ff6a2af to eea8ceb Compare November 2, 2026 17:29
Copilot AI balanced review requested due to automatic review settings November 2, 2026 17:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Vincent Biret (@baywet) Please take a look into this.
Thanks.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unvalidated numeric enum values can inject source code into generated SDKs, while fractional values, defaults, and flags can cause compilation failures or loss of wire values.

6 open issues

Review effort: Balanced

x.GetValue<string>() is string value &&
!string.IsNullOrEmpty(value)); // number and boolean enums are not supported
!string.IsNullOrEmpty(value)) ||
x.GetValueKind() is JsonValueKind.Number);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the Java constructor default emitter in \Java/CodeMethodWriter.cs\ to resolve the matching enum option and emit double-quoted string literals (e.g. \Status.forValue(\10)), matching the \ValuedEnum\ signature defined on the Java enum. Added a constructor default regression test in \CodeMethodWriterTests.cs.

Comment thread src/Kiota.Builder/KiotaBuilder.cs Outdated
Comment on lines +2390 to +2391
var isNumeric = schema.Type is JsonSchemaType.Integer or JsonSchemaType.Number
|| (schema.Enum is { Count: > 0 } && schema.Enum.OfType<JsonValue>().All(static x => x.GetValueKind() is JsonValueKind.Number));

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added RevertFractionalEnumsToPrimitives in CommonLanguageRefiner.cs and invoked it in CSharpRefiner.cs ( loat/double) and GoRefiner.cs ( loat32/ loat64) to downgrade non-integral enums back to primitive types before emission. Additionally guarded both CSharp/CodeEnumWriter.cs and Go/CodeEnumWriter.cs to reject fractional enums with descriptive exceptions if encountered directly, backed by refiner and writer unit tests.

{
Name = declarationName,
Flags = enumFlagsExtension?.IsFlags ?? false,
IsNumeric = isNumeric,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated CSharp/CodeMethodWriter.cs to resolve default values against the enum's options matching by SerializationName, WireName, or Name. This ensures customized option names (such as those populated via x-ms-enum) are properly selected instead of re-cleaning the raw numeric literal. Added unit tests for default value resolution in constructor emission.

writer.WriteLine($"{option.Name.ToFirstCharacterUpperCase()}{(codeElement.Flags ? " = " + GetEnumFlag(idx) : string.Empty)},");
if (codeElement.IsNumeric)
{
writer.WriteLine($"{option.Name.ToFirstCharacterUpperCase()} = {option.SerializationName},");

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added IsNumericEnum() validation in OpenApiSchemaExtensions.cs to require that all enum values are valid numbers before flagging the schema as a numeric enum. In addition, added strict numeric literal parsing across all target writers (C#, Go, Python, TypeScript, PHP, and Ruby) to reject non-numeric or hostile payloads prior to emission, along with hostile-payload regression tests for each writer.


writer.WriteLine(); // gofmt: exactly one blank line before each top-level declaration
if (isMultiValue)
if (codeElement.IsNumeric)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Scoped the math import in GoRefiner.cs to non-numeric flags enums (enum.Flags && !@enum.IsNumeric), preventing unused import compiler errors. In Go/CodeEnumWriter.cs, implemented slice iteration over defined flag options in String() to support composite flag values (e.g. 1 | 2) cleanly without needing math.Pow. Covered with Go refiner and writer unit tests.

writer.WriteLine("from enum import Enum");
writer.WriteLine();
writer.WriteLine($"class {codeElement.Name}(str, Enum):");
var baseType = codeElement.IsNumeric ? (string.Equals(codeElement.Format, "float", StringComparison.OrdinalIgnoreCase) || string.Equals(codeElement.Format, "double", StringComparison.OrdinalIgnoreCase) ? "float" : "int") : "str";

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added IsFractional on CodeEnum to detect floating-point formats and options with fractional components, and updated Python/CodeEnumWriter.cs to inherit from loat, Enum whenever IsFractional is true. This preserves member identities and exact wire values without integer truncation. Added unit tests covering fractional enums with and without explicit format.

Copilot AI balanced review requested due to automatic review settings November 20, 2026 18:28
- Java defaults: format wire values as string literals for forValue(...) in CodeMethodWriter.
- Fractional enums: revert to primitive floating types in C# and Go refiners, and throw in writers if encountered.
- C# defaults: resolve enum default values by matching SerializationName, WireName, or Name.
- Literal validation: validate numeric literals in C#, Go, Python, TypeScript, PHP, and Ruby writers to prevent code injection.
- Go flags & math import: format numeric flags enums in Go without math.Pow and restrict math package import to non-numeric flags enums.
- Python fractional enums: inherit from float, Enum when enum is fractional.
- Tests & formatting: update MapsNumberEnumToDoubleTypeAsync for numeric enum return type, format all modified files with UTF-8 BOM, and add comprehensive unit tests.

Signed-off-by: Hardik Kaurani <hardikkaurani1@gmail.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet),

I've addressed all review feedback from Copilot and resolved the CI test failures:

  • Java default value emission: Updated Java/CodeMethodWriter.cs to resolve numeric enum options and emit double-quoted string literals for forValue("..."), matching the ValuedEnum<String> contract.
  • Fractional enums (C# & Go): Added refiner logic (RevertFractionalEnumsToPrimitives) in CSharpRefiner.cs and GoRefiner.cs to revert non-integral enums to primitive floating types (float/double and float32/float64), and added guard checks in writers to reject unhandled fractional enums.
  • C# default value resolution: Updated CSharp/CodeMethodWriter.cs to match options by SerializationName, WireName, or Name, ensuring options customized via x-ms-enum are properly resolved rather than re-cleaning raw numeric literals.
  • Numeric literal validation: Required all enum values in OpenApiSchemaExtensions.IsNumericEnum to be valid numbers, and added strict numeric literal validation across C#, Go, Python, TypeScript, PHP, and Ruby writers to reject non-numeric or hostile payloads prior to emission.
  • Go numeric flags & math import: Replaced the unused math.Pow emission in Go numeric flags with slice iteration over defined options in String(), and scoped the math package import in GoRefiner.cs to non-numeric flags enums (@enum.Flags && !@enum.IsNumeric).
  • Python fractional enums: Enabled Python/CodeEnumWriter.cs to inherit from float, Enum when values have fractional parts or float formats, preventing integer truncation and member aliasing.
  • Test suite & formatting: Updated MapsNumberEnumToDoubleTypeAsync to verify the generated numeric enum response type, formatted all modified files to adhere to .editorconfig (including UTF-8 BOM encoding), and verified that all 2,990 builder tests and 18 CLI tests pass locally.

Ready for review when you have a moment.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for numerical enum values

2 participants